---
title: PdfAPI overview
summary: Purpose, consumers, business context, and capability summary for the PdfAPI REST API.
status: draft
owner: Not determined from source
last_reviewed: 2026-09-17
library: PdfAPI
reference_type: embedded
---

# PdfAPI overview

PdfAPI converts documents to PDF, merges PDF documents, extracts page ranges, and inspects or validates PDF content on behalf of upstream systems, persisting a tracking record of each conversion/merge request in the Oracle `IMG` schema so callers can poll or download the result later.

## Purpose
- Convert uploaded documents (Office formats, images, plain text, and existing PDFs) to PDF or PDF/A output, selecting between a Syncfusion-based processor (default) and an ActivePDF-based processor by configuration.
- Merge multiple source documents — converting any non-PDF input first — into a single PDF output.
- Extract one or more page ranges from a source PDF into a new document.
- Track the lifecycle of convert/merge requests (`Scheduled` → `Processing` → terminal) in the Oracle `IMG` schema, and allow callers to poll status or download the finished output by tracking id.
- Inspect PDF content without persistence: page count, form-field presence, form-field flattening, PDF/PDF-A validity, and PDF version.
- Publish build/version metadata for the deployed service.

## Business context

PdfAPI is the imaging system's PDF-processing back end: it performs document conversion, merge, and extraction on behalf of upstream systems that need PDF output, and it owns the tracking records that let a caller confirm a conversion succeeded before acting on the result. If the service is unavailable, upstream systems cannot convert or merge documents into PDF, cannot extract page ranges, and cannot resolve tracking status for in-flight requests.

| Attribute | Value |
| --- | --- |
| Business domain | PDF document processing and imaging support |
| Owning team | Not determined from source** |
| Data ownership | `PDFTracking` and its lookup tables (`PDFStatusCode`, `PDFTrackingCode`, `PDFApplicationErrorCode`) in the Oracle `IMG` schema |
| Criticality | Not determined from source** |

## Consumers

| Consumer | Type | Endpoints used | Authentication | Notes |
| --- | --- | --- | --- | --- |
| `PdfAPI.Client` (generated NuGet client, `Scripts\PdfAPI.Client\PdfAPI.Client.nuspec`) | Generated client package | [`POST v1/convert`](endpoints/convert-controller.md#post-v1%2Fconvert), and the other four endpoints called by `PdfClient.cs` | None in code | `PdfClient` builds its base URI as `{url}/v1/` and issues `PostJson<>`/`GetResult<>` calls* |
| Callers reaching the service directly over HTTP | Not determined from source** | All 13 endpoints | None in code | No deployment definition or API-gateway configuration was found in this repository identifying additional callers |

## Base address

| Environment | Base address | Resolved from |
| --- | --- | --- |
| DEV | Not determined from source** | `ApplicationHost = entdev01` (`PdfAPI\Web.config`) names the environment tier only; no base-URL host value is declared in this repository |
| TEST | Not determined from source** | Unknown** |
| PROD | Not determined from source** | Unknown** |

## Capability summary

| Capability | Owning component | Endpoints | Description |
| --- | --- | --- | --- |
| Document conversion | `ConvertController` | [`POST v1/convert`](endpoints/convert-controller.md#post-v1%2Fconvert), [`POST v1/convert/{fileExtension}`](endpoints/convert-controller.md#post-v1%2Fconvert%2F%7Bfileextension%7D) | Converts a source document to PDF or PDF/A via the selected processor |
| PDF merge | `MergeController` | [`POST v1/merge`](endpoints/merge-controller.md#post-v1%2Fmerge) | Converts non-PDF inputs and merges all documents into a single PDF |
| Page extraction | `ExtractController` | [`POST v1/extract`](endpoints/extract-controller.md#post-v1%2Fextract) | Extracts one or more page ranges from a source PDF |
| Tracking status and download | `LegacyController`, `InfoController` | [`GET v1/legacy/download/{trackingId}`](endpoints/legacy-controller.md#get-v1%2Flegacy%2Fdownload%2F%7Btrackingid%7D), [`GET v1/info/track/{trackingId}`](endpoints/info-controller.md#get-v1%2Finfo%2Ftrack%2F%7Btrackingid%7D) | Polls or downloads the result of a tracked conversion/merge request |
| PDF inspection and validation | `InfoController` | [`POST v1/info/pages/count`](endpoints/info-controller.md#post-v1%2Finfo%2Fpages%2Fcount), [`POST v1/info/fields/exist`](endpoints/info-controller.md#post-v1%2Finfo%2Ffields%2Fexist), [`POST v1/info/fields/flatten`](endpoints/info-controller.md#post-v1%2Finfo%2Ffields%2Fflatten), [`POST v1/info/validate`](endpoints/info-controller.md#post-v1%2Finfo%2Fvalidate), [`POST v1/info/validate/pdfa`](endpoints/info-controller.md#post-v1%2Finfo%2Fvalidate%2Fpdfa), [`POST v1/info/version`](endpoints/info-controller.md#post-v1%2Finfo%2Fversion) | Page count, form-field presence/flattening, PDF/PDF-A validity, and PDF version — no persistence |
| Build metadata | `ApiInfoController` | [`GET buildVersion`](endpoints/api-info-controller.md#get-buildversion) | Returns build/version information for the deployed service |

## Request and response format

| Aspect | Finding |
| --- | --- |
| Media types | JSON only — `config.Formatters.XmlFormatter` removed (`PdfAPI\App_Start\WebApiConfig.cs`) |
| Serializer settings | Framework defaults — no `JsonSerializerSettings`, contract resolver, or converter is configured, so property names serialize in PascalCase* |
| Response envelope | DTOs returned directly (`PdfResult`, `PdfTrackingInfo`, or primitives via `Ok(result)` or a bare return value); the `ApiResponseHandler` message handler additionally wraps every response but its exact envelope shape is implemented inside the `SAIF.Web.API` package and is not visible in this repository** |

## Non-documented artifacts

- Stock ASP.NET MVC scaffolding is present in this repository but is not an application surface and is excluded from this document set entirely: `Controllers\HomeController.cs`, `Views\**`, `App_Start\RouteConfig.cs`, `App_Start\BundleConfig.cs`, `App_Start\FilterConfig.cs`, `Content\**`, `Scripts\**`, `fonts\**`, and `Areas\HelpPage\**`.

## Related documentation
- [API index](index.md)
- [Architecture](architecture.md)
- [Endpoints](endpoints.md)
- [Authentication and authorization](authentication-authorization.md)
- [Dependencies](dependencies.md)
- [Configuration](configuration.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Data model](data-model.md)
- [Operational runbook](operational-runbook.md)
- [Tech debt](tech-debt.md)

> **Note:** Statements marked with `*` were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with `**` could not be confirmed; treat as unknown until verified.

## Sources
- PdfAPI\Web.config
- PdfAPI\App_Start\WebApiConfig.cs
- PdfAPI\Controllers\v1\ConvertController.cs
- PdfAPI\Controllers\v1\ExtractController.cs
- PdfAPI\Controllers\v1\MergeController.cs
- PdfAPI\Controllers\v1\LegacyController.cs
- PdfAPI\Controllers\v1\InfoController.cs
- PdfAPI\Controllers\v1\ApiInfoController.cs
- PdfAPI\Services\PdfTrackingService.cs
- PdfAPI.Client\PdfClient.cs
- Scripts\PdfAPI.Client\PdfAPI.Client.nuspec